From fd6faabe16e6722dafaafa3c0b888d6cdb838716 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 27 Feb 2021 17:49:35 -0500 Subject: [PATCH] actionable: Convert docs --- gtk/gtkactionable.c | 106 ++++++++++++++++++-------------------------- 1 file changed, 44 insertions(+), 62 deletions(-) diff --git a/gtk/gtkactionable.c b/gtk/gtkactionable.c index f2a38fe71d..974b881d2a 100644 --- a/gtk/gtkactionable.c +++ b/gtk/gtkactionable.c @@ -25,29 +25,21 @@ #include "gtkintl.h" /** - * SECTION:gtkactionable - * @title: GtkActionable - * @short_description: An interface for widgets that can be associated - * with actions + * GtkActionable: * - * This interface provides a convenient way of associating widgets with - * actions on a #GtkApplicationWindow or #GtkApplication. + * The `GtkActionable` interface provides a convenient way of asscociating + * widgets with actions. * - * It primarily consists of two properties: #GtkActionable:action-name - * and #GtkActionable:action-target. There are also some convenience APIs - * for setting these properties. + * It primarily consists of two properties: [property@Gtk.Actionable:action-name] + * and [property@Gtk.Actionable:action-target]. There are also some convenience + * APIs for setting these properties. * * The action will be looked up in action groups that are found among * the widgets ancestors. Most commonly, these will be the actions with - * the “win.” or “app.” prefix that are associated with the #GtkApplicationWindow - * or #GtkApplication, but other action groups that are added with - * gtk_widget_insert_action_group() will be consulted as well. - **/ - -/** - * GtkActionable: - * - * An opaque pointer type. + * the “win.” or “app.” prefix that are associated with the + * `GtkApplicationWindow` or `GtkApplication`, but other action groups that + * are added with [method@Gtk.Widget.insert_action_group] will be consulted + * as well. **/ /** @@ -57,7 +49,7 @@ * @get_action_target_value: virtual function for gtk_actionable_get_action_target_value() * @set_action_target_value: virtual function for gtk_actionable_set_action_target_value() * - * The interface vtable for #GtkActionable. + * The interface vtable for `GtkActionable`. **/ G_DEFINE_INTERFACE (GtkActionable, gtk_actionable, GTK_TYPE_WIDGET) @@ -77,15 +69,13 @@ gtk_actionable_default_init (GtkActionableInterface *iface) } /** - * gtk_actionable_get_action_name: - * @actionable: a #GtkActionable widget + * gtk_actionable_get_action_name: (attributes org.gtk.Property.get=action-name) + * @actionable: a `GtkActionable` widget * * Gets the action name for @actionable. * - * See gtk_actionable_set_action_name() for more information. - * * Returns: (nullable): the action name, or %NULL if none is set - **/ + */ const char * gtk_actionable_get_action_name (GtkActionable *actionable) { @@ -96,22 +86,24 @@ gtk_actionable_get_action_name (GtkActionable *actionable) } /** - * gtk_actionable_set_action_name: - * @actionable: a #GtkActionable widget + * gtk_actionable_set_action_name: (attributes org.gtk.Property.set=action-name) + * @actionable: a `GtkActionable` widget * @action_name: (nullable): an action name, or %NULL * * Specifies the name of the action with which this widget should be - * associated. If @action_name is %NULL then the widget will be - * unassociated from any previous action. + * associated. + * + * If @action_name is %NULL then the widget will be unassociated from + * any previous action. * * Usually this function is used when the widget is located (or will be - * located) within the hierarchy of a #GtkApplicationWindow. + * located) within the hierarchy of a `GtkApplicationWindow`. * * Names are of the form “win.save” or “app.quit” for actions on the - * containing #GtkApplicationWindow or its associated #GtkApplication, - * respectively. This is the same form used for actions in the #GMenu + * containing `GtkApplicationWindow` or its associated `GtkApplication`, + * respectively. This is the same form used for actions in the `GMenu` * associated with the window. - **/ + */ void gtk_actionable_set_action_name (GtkActionable *actionable, const char *action_name) @@ -123,15 +115,13 @@ gtk_actionable_set_action_name (GtkActionable *actionable, } /** - * gtk_actionable_get_action_target_value: - * @actionable: a #GtkActionable widget + * gtk_actionable_get_action_target_value: (attributes org.gtk.Method.get_property=action-target) + * @actionable: a `GtkActionable` widget * * Gets the current target value of @actionable. * - * See gtk_actionable_set_action_target_value() for more information. - * * Returns: (nullable) (transfer none): the current target value - **/ + */ GVariant * gtk_actionable_get_action_target_value (GtkActionable *actionable) { @@ -142,24 +132,23 @@ gtk_actionable_get_action_target_value (GtkActionable *actionable) } /** - * gtk_actionable_set_action_target_value: - * @actionable: a #GtkActionable widget + * gtk_actionable_set_action_target_value: (attributes org.gtk.Method.set_property=action-target) + * @actionable: a `GtkActionable` widget * @target_value: (nullable): a #GVariant to set as the target value, or %NULL * * Sets the target value of an actionable widget. * * If @target_value is %NULL then the target value is unset. * - * The target value has two purposes. First, it is used as the - * parameter to activation of the action associated with the - * #GtkActionable widget. Second, it is used to determine if the widget - * should be rendered as “active” — the widget is active if the state - * is equal to the given target. + * The target value has two purposes. First, it is used as the parameter + * to activation of the action associated with the `GtkActionable` widget. + * Second, it is used to determine if the widget should be rendered as + * “active” — the widget is active if the state is equal to the given target. * - * Consider the example of associating a set of buttons with a #GAction - * with string state in a typical “radio button” situation. Each button + * Consider the example of associating a set of buttons with a `GAction` + * with string state in a typical “radio button” situation. Each button * will be associated with the same action, but with a different target - * value for that action. Clicking on a particular button will activate + * value for that action. Clicking on a particular button will activate * the action with the target of that button, which will typically cause * the action’s state to change to that value. Since the action’s state * is now equal to the target value of the button, the button will now @@ -178,7 +167,7 @@ gtk_actionable_set_action_target_value (GtkActionable *actionable, /** * gtk_actionable_set_action_target: - * @actionable: a #GtkActionable widget + * @actionable: a `GtkActionable` widget * @format_string: a GVariant format string * @...: arguments appropriate for @format_string * @@ -186,12 +175,12 @@ gtk_actionable_set_action_target_value (GtkActionable *actionable, * * This is a convenience function that calls g_variant_new() for * @format_string and uses the result to call - * gtk_actionable_set_action_target_value(). + * [method@Gtk.Actionable.set_action_target_value]. * - * If you are setting a string-valued target and want to set the action - * name at the same time, you can use - * gtk_actionable_set_detailed_action_name (). - **/ + * If you are setting a string-valued target and want to set + * the action name at the same time, you can use + * [method@Gtk.Actionable.set_detailed_action_name]. + */ void gtk_actionable_set_action_target (GtkActionable *actionable, const char *format_string, @@ -206,7 +195,7 @@ gtk_actionable_set_action_target (GtkActionable *actionable, /** * gtk_actionable_set_detailed_action_name: - * @actionable: a #GtkActionable widget + * @actionable: a `GtkActionable` widget * @detailed_action_name: the detailed action name * * Sets the action-name and associated string target value of an @@ -214,13 +203,7 @@ gtk_actionable_set_action_target (GtkActionable *actionable, * * @detailed_action_name is a string in the format accepted by * g_action_parse_detailed_name(). - * - * (Note that prior to version 3.22.25, - * this function is only usable for actions with a simple "s" target, and - * @detailed_action_name must be of the form `"action::target"` where - * `action` is the action name and `target` is the string to use - * as the target.) - **/ + */ void gtk_actionable_set_detailed_action_name (GtkActionable *actionable, const char *detailed_action_name) @@ -246,4 +229,3 @@ gtk_actionable_set_detailed_action_name (GtkActionable *actionable, g_variant_unref (target); g_free (name); } - -- 2.30.2